System Booster

home *** CD-ROM | disk | FTP | other *** search

/ System Booster / System Booster.iso / Commodities / AddTools / AddToolsDoc-E < prev next >

Wrap

Text File | 1996-09-26 | 17KB | 375 lines

$VER: AddTools.doc 1.20 (29.11.93) © Alessandro Sala AddTools version 1.20 29-Nov-1993 Copyright © 1993 By Alessandro Sala Requires AmigaOS v2.04 ( Kickstart v37 ) or later ------------ Disclaimer ------------ This program is provided "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranty of fitness for a particular purpose. Though every care has been taken to make this program system-friendly and bugs-free, the entire risk as to the results, reliability and performance of this program is assumed by you. ------------------ Copyright notice ------------------ This program is "FreeWare": it can be freely copied and distributed for non-commercial purposes, provided that no file is added to or removed from the distribution archive and no charge, beside a nominal media cost, is requested. Fred Fish is, of course, explicitly allowed to put this program on his great disk library. Nevertheless the program remains COPYRIGHT of the Author: you cannot patch, reverse engineer or otherwise modify the program, the documentation and every other file found in the distribution archive. Compressing in executable form is only allowed for personal use, not when the program is being distributed: LHARC'ing in an archival form is explicitly allowed for distribution convenience. Furthermore you cannot embed the program in any other software without the written permission of the author. ------------------------------------ Contents of the distribution archive ------------------------------------ AddTools : The main program AddToolsData : Configuration file example AddToolsDoc-E : English documentation Catalogs : Drawer AddTools.ct : Empty translation file italiano : Drawer AddTools.catalog : Italian language support file MTCopy : Example AmigaDos script for use with AddTools AddTools.info \ AddToolsData.info | AddToolsDoc-E.info | : Related icons Catalogs.info | AddTools.ct.info | MTCopy.info / 1. Introduction --------------- AddTools is a very simple utility, written mainly to experiment with the new applications menu ( "Tools" ) of AmigaOS release 2, but I found it very useful so I decided to release it as Freeware with the hope that someone else will find it convenient. The program allows you to add your own items to the "Tools" menu of AmigaOS_2.04's Workbench Screen. Unlike other menu utilities, which only add the ability to run programs by menu, AddTools can also pass them some parameters on "the fly" by selecting some icons ( from now on called " icon parameters" ), before choosing the desired menu item. You can also provide default values if no icons are selected, and you can decide if the the program must be run in either synchronous or asynchronous mode when multiple icon parameters are selected. -------------------------- Changes since version 1.11 -------------------------- If you already know AddTools v1.11, here are some major differences from the previous version: -- New BREAK_WARN tooltype: if set, AddTools will open a requester to warn you whenever it receives a control-c signal. -- New EXTRA_ITEM tooltype: AddTools will add the 'AddTools...' item to the tools menu only if this tooltype is set. -- New WINDOW= tooltype, allowing you to configure the default output window for the programs you run using the tools menu. -- Ability to individually configure the output window for every menu item. ------------ Installation ------------ To install AddTools you can simply copy it in some drawer, typically your SYS:WBStartup drawer. Then create the configuration file AddToolsData, as explained below, and put it in your S: volume ( normally the SYS:S drawer ) or in the same directory as AddTools. If you have OS 2.1 or later and you want to take advantage of the localization, you must also copy the 'catalogs' drawer, found in the AddTools distribution archive, into the same drawer as AddTools, or you can copy the 'AddTools.catalog' file ( found in the 'catalogs/<language>/' drawer ) into your 'LOCALE:catalogs/<language>/' drawer. If your language is not currently available, you can fill in the empty translation file found in the catalogs drawer ( catalogs/AddTools.ct ) and send it to me by E-Mail ( the address is at the end of this file ). I will create a new '<your-language>/AddTools.catalog' file and E-Mail it to you as soon as possible, and the next version of AddTools will support one more language ! 2. Configuration and usage -------------------------- -2.1- Tooltypes You can set various tooltypes in the AddTools' icon: BREAK_WARN : If set, AddTools will open a requester whenever it receives a control-c signal, informing you that it is quitting. EXTRA_ITEM : If set, an extra item, named 'AddTools...', will be added at the bottom of the tools menu. Selecting this item, a requester will open, asking you if you want to quit AddTools. WINDOW=<win_desc> : With this tooltype you can configure the window that AddTool provides to every program you run from the tools menu. The default <win_desc> is: CON:0/40/640/150/AddTools/auto/close/wait which means: a 640 pixels wide, 150 pixels tall window, located at the top of the screen, and 40 pixels from the left border. The window's title is 'AddTools', it will open only if the program actually does some output, it will have a close button and it will not close automatically, when the program ends. For more info about window descriptions, see your AmigaDOS manual. The window can also be individually configured for every menu item: see below. -2.2- The configuration file AddTools can be started from workbench by double-clicking its icon or by placing it in your WBStartup drawer to have it activated every time you boot; in this case remember to add the "DONOTWAIT" ToolType. You can also run AddTools from a CLI or from your user-startup; in this case use the RUN command to start AddTools in the background. When AddTools is started, it looks in the current directory to see if a configuration file named "AddToolsData" exists: if not, it then searches in the S: volume (typically your SYS:S drawer) and aborts if it doesn't find there the configuration file. The "AddToolsData" file contains the description of the various menu items you want to add to the Tools menu. Every item is defined by three lines with the following format: <Line 1> Menu_item_text <Line 2> Menu_item_associated_command_line_with_parameters <Line 3> Synchronous/Asynchronous_mode_flag_&_output_window these three lines are repeated for every menu item you want to add. Here comes an explanation of every line: Line 1 : Menu item text : This is the text you want to be displayed in the tools menu: note that shortcuts are not available at the moment. Line 2 : Command line : This will normally be the complete path and name of the program you want to be run when choosing this menu item, possibly followed by parameters. If you want to pass this program possible icons as parameters you must include a special char sequence in the command line, as explained below. Line 3 : Sync/Async&out : This will be either an "A" or an "S" char to indicate A)synchronous or S)ynchronous execution mode (see below). After this first char, you can optionally put a '|' character followed by window description which will be used as the output window for the command line of this menu item. E.g. A|CON:10/30/300/200/MyWindow/close/auto will give you a 300 pixels wide, 200 pixels tall window, located at 10 pixels from the left border and 30 pixels from the top border. The title of the window will be 'MyWindow', it will have a close button ('close' option) and it will open only if the program prints something ('auto' option). When the program ends, this window will automatically close. For more info, see your AmigaDOS manual. In the distribution archive you can find an example of the 'AddToolsData' configuration file. -2.3- Synchronous vs. Asynchronous mode If, in the third line of a menu item definition, you specified asynchronous mode, AddTools will execute the associated command line asynchronously ( as you might expect ! ), that is not waiting for the completion of the program execution. This is the best way if the program has fixed parameters, directly passed in by the command line you provided. This mode can also be useful with icons parameters, but I will explain this later. On the other hand, in synchronous mode, if you select more than one icon parameter, AddTools will wait until the program execution has completed before handling successive icon parameters. The usefulness of this mode will come clear in the next section when I' ll discuss of multiple icon parameters. -2.4- Icon parameters If, before choosing a menu item, you select one or more icons, the menu item associated program will be able to see them as if they were command line parameters. To enable this feature for a particular item, you must specify in the item's command line a string with the following format: [<default_params>] where '<default_params>' is whatever string you want and '[' and']' are simply what they seem: open and closed square brackets ! -2.4.1- Single icon parameter When an icon parameter is selected, its complete volume:path/name string will be substituted to the <default_params> string, and the two square brackets will be removed. The resulting command line is then executed. If no icon is selected when the menu item is chosen, no substitution will occur and the square brackets will be removed, so the resulting command line will contain the <default_params> string which will act as a default parameter block. Note that the [xxx] can be put everywhere in the command line, even mixed with other parameters which will be preserved after substitution. Example: C:Ed [temp] WIDTH=64 this line will execute the editor Ed with a 64 columns wide display and a 'temp' filename if no icon is selected, otherwise the selected icon will be edited. Note that you can also set <default_params> to a null string, i.e. '[]', and in this case no default values will be passed if you don't select an icon ( similar to the AmigaDOS command 'alias' ). -2.4.2- Multiple icon parameters If more than one icon is selected when the menu item is activated, all the icons will be passed in as parameters in the following way: the first icon's volume:path/name gets substituted and the command line is executed; if the execution mode is synchronous AddTools waits for the program execution to complete, then it substitutes the second icon, executes the resulting command line and so on until all icons are processed. If asynchronous mode is set, AddTools will immediately continue substituting icons and executing command lines: this way you will get every icon concurrently processed by its own copy of the program associated with the menu item. From version 1.10 you can specify more than one [<default_params>] string in the command line. In this way the first icon you selected will be substituted in place of the first parameter, the second icon in place of the second parameter and so on. If the number of icons selected is greater than the number of parameters, this process is repeated - immediately if synchronous mode is set, when the program returns, otherwise - on a new copy of the command line, until all icons are processed. 3. Terminating AddTools ----------------------- You can execute as many copies of AddTools as you want, but to remove one or more of them (and the associated menu items) from the memory you can select the appropriate 'AddTools ...' menu item (if enabled) and answer 'Yes' to the subsequent requester. If you launched AddTools from Workbench or through the WBStartup drawer, you can also terminate AddTools by sending a BREAK signal (CTRL-C) through a task utility (such as TaskX by Steve Tibbett). If, on the other hand, AddTools was run from a CLI you can use the following procedure: 1) Open a CLI 2) Issue the 'STATUS' command and note the process number of AddTools 3) Issue 'BREAK <n> C' where <n> is the process number noted above 4. Criticism and suggestions ---------------------------- I hope you will find AddTools useful, and if you have any criticism, suggestions, bug report, ideas for enhancements in possible future versions, you can write ( in Italian or English ) at the following address: Alessandro Sala Via A. Grandi, 16 20014 Nerviano (MI) Italy If you have E-Mail capability you can also contact me at the following Internet address (at least until the end of February 1994): tser1506@cdc835.cdc.polimi.it Thank you ********************************************************************************** History ********************************************************************************** ------------ Version 1.20 ------------ -- New BREAK_WARN tooltype: if set, AddTools will open a requester to warn you whenever it receives a control-c signal. -- New EXTRA_ITEM tooltype: AddTools will add the 'AddTools...' item to the tools menu only if this tooltype is set. -- New WINDOW= tooltype, allowing you to configure the default output window for the programs you run using the tools menu (Doug Hart inspired me with this and the following feature). -- Added the ability to individually configure the output window for every menu item. ------------ Version 1.11 ------------ -- Corrected various mistakes in English inside this file ( further corrections in the next version !!! ). -- In version 1.00 there was a limit of 10 menu items: now it has been removed. -- Using synchronous items no longer locks AddTools until all parameters have been processed. Now there is an independent task handling synchronous items. -- Now supports localization if you have OS 2.1 or later; currently supported languages are: English (built-in) Italian -- If you choose an item with less than 2 icons selected ( that is 1 or none ) it will now run in asynchronous mode regardless of the sync/async flag. -- New menu item, named 'AddTools...', automatically added at the end of user items to allow simpler termination of AddTools. -- Fixed a bug in icon parameters handling code: if an item had default parameters inside the '[]', the command line after the ']' was ignored. -- Added support for multiple '[<default_params>]' strings in a single command line. ------------ Version 1.10 ------------ Internal beta version ( never released ). ------------ Version 1.00 ------------ First release!